✨ Feat: add Thin Waist address validation utilities and integrate into echo example #811

yashksaini-coder · 2025-08-08T19:59:34Z

What was wrong?

There was no integration for thin waist address validation.

Issue #804

How was it fixed?

Implements Phase 1 & partial Phase 2 of issue #804 by introducing Thin Waist Address Validation utilities and updating the echo example to use them, Using the multiaddr.

New utility module: libp2p/utils/address_validation.py
- get_available_interfaces
- get_optimal_binding_address
- expand_wildcard_address
- Safe fallbacks when Thin Waist functions are not present in multiaddr.utils
Re-exported utilities in libp2p/utils/__init__.py
Updated examples/echo/echo.py:
- Replaced hardcoded /ip4/0.0.0.0/tcp/{port} with get_optimal_binding_address
- Added interface discovery logging
Added advanced demo: examples/advanced/network_discovery.py
Added tests:
- tests/utils/test_address_validation.py
- tests/examples/test_echo_thin_waist.py (light integration)

Why

Enables dynamic discovery of bindable interfaces (IPv4 & IPv6 where available)
Provides a clean abstraction for examples to avoid hardcoding wildcard addresses
Demonstrates best practices for future example migrations
Maintains backward compatibility (graceful fallbacks if Thin Waist APIs not installed)

Backward Compatibility

If multiaddr.utils.get_thin_waist_addresses / get_network_addrs are unavailable, utilities fallback to conservative defaults.
Existing behavior (binding on wildcard / loopback) still achievable.

To-Do

Utilities implemented with safe fallbacks
Echo example migrated
Tests added & passing locally
No breaking public API changes
Clean up commit history
Add or update documentation related to these changes
Add entry to the release notes

…tilities - Added `network_discover.py` to demonstrate Thin Waist address handling. - Introduced `address_validation.py` with functions for discovering available network interfaces, expanding wildcard addresses, and determining optimal binding addresses. - Included fallback mechanisms for environments lacking Thin Waist support.

- Replaced hardcoded listen address with `get_optimal_binding_address` for improved flexibility. - Imported address validation utilities in `echo.py` and updated `__init__.py` to include new functions.

- Introduced `test_echo_thin_waist.py` to validate the echo example's output for Thin Waist lines. - Added `test_address_validation.py` to cover functions for available interfaces, optimal binding addresses, and wildcard address expansion. - Included parameterized tests and environment checks for IPv6 support.

acul71 · 2025-08-09T17:56:39Z

Hi @yashksaini-coder, ping me if you need help.
you can run make PR and make docs to check everything is ok

yashksaini-coder · 2025-08-10T07:43:31Z

Hi @yashksaini-coder, ping me if you need help. you can run make PR and make docs to check everything is ok

Right now, I've created a draft PR to introduce the multiadd thin waist address. with integration to examples and tests, could you give me feedback on this approach. I've only done Phase 1 + 2 (partially) based on the issue #804

acul71 · 2025-08-10T15:23:57Z

tests/examples/test_echo_thin_waist.py

@@ -0,0 +1,51 @@
+import asyncio


Please use Trio we don't use asyncio (for uniformity in all code base)

acul71 · 2025-08-10T15:55:39Z

@yashksaini-coder

Can you modify echo.py so that it "mimic" javascript echo, exposing all available interfaces?

Current echo.py

(venv) luca@r17:~/PNL_Launchpad_Curriculum/Libp2p/tmp/yashksaini-coder/py-libp2p$ python examples/echo/echo.py
I am 16Uiu2HAmRxqPcNXm9KAUAVKyQkpXF8c8r7S6jdpGK6K963w9Puwk
Run this from the same folder in another console:

echo-demo -d /ip4/192.168.136.148/tcp/33387/p2p/16Uiu2HAmRxqPcNXm9KAUAVKyQkpXF8c8r7S6jdpGK6K963w9Puwk

Waiting for incoming connections...

javascript echo

luca@r17:~/PNL_Launchpad_Curriculum/Libp2p/js-libp2p-examples/examples/js-libp2p-example-chat$ node src/listener.js 
Listener ready, listening on:
/ip4/127.0.0.1/tcp/10333/p2p/12D3KooWCS6QSMEbtt77pWeB618W824aGVxhLhPEPaCUMGMvBhuk
/ip4/192.168.136.148/tcp/10333/p2p/12D3KooWCS6QSMEbtt77pWeB618W824aGVxhLhPEPaCUMGMvBhuk
/ip4/10.149.6.41/tcp/10333/p2p/12D3KooWCS6QSMEbtt77pWeB618W824aGVxhLhPEPaCUMGMvBhuk

Desired python echo

echo.py
I am 16Uiu2HAmRxqPcNXm9KAUAVKyQkpXF8c8r7S6jdpGK6K963w9Puwk
Listener ready, listening on:
/ip4/127.0.0.1/tcp/10333/p2p/16Uiu2HAmRxqPcNXm9KAUAVKyQkpXF8c8r7S6jdpGK6K963w9Puwk
/ip4/192.168.136.148/tcp/10333/p2p/16Uiu2HAmRxqPcNXm9KAUAVKyQkpXF8c8r7S6jdpGK6K963w9Puwk
/ip4/10.149.6.41/tcp/10333/p2p/16Uiu2HAmRxqPcNXm9KAUAVKyQkpXF8c8r7S6jdpGK6K963w9Puwk

Run this from the same folder in another console:

echo-demo -d /ip4/192.168.136.148/tcp/33387/p2p/16Uiu2HAmRxqPcNXm9KAUAVKyQkpXF8c8r7S6jdpGK6K963w9Puwk

Waiting for incoming connections...

yashksaini-coder · 2025-08-10T16:05:06Z

@yashksaini-coder

Can you modify echo.py so that it "mimic" javascript echo, exposing all available interfaces?

Current echo.py

(venv) luca@r17:~/PNL_Launchpad_Curriculum/Libp2p/tmp/yashksaini-coder/py-libp2p$ python examples/echo/echo.py
I am 16Uiu2HAmRxqPcNXm9KAUAVKyQkpXF8c8r7S6jdpGK6K963w9Puwk
Run this from the same folder in another console:

echo-demo -d /ip4/192.168.136.148/tcp/33387/p2p/16Uiu2HAmRxqPcNXm9KAUAVKyQkpXF8c8r7S6jdpGK6K963w9Puwk

Waiting for incoming connections...

javascript echo

luca@r17:~/PNL_Launchpad_Curriculum/Libp2p/js-libp2p-examples/examples/js-libp2p-example-chat$ node src/listener.js 
Listener ready, listening on:
/ip4/127.0.0.1/tcp/10333/p2p/12D3KooWCS6QSMEbtt77pWeB618W824aGVxhLhPEPaCUMGMvBhuk
/ip4/192.168.136.148/tcp/10333/p2p/12D3KooWCS6QSMEbtt77pWeB618W824aGVxhLhPEPaCUMGMvBhuk
/ip4/10.149.6.41/tcp/10333/p2p/12D3KooWCS6QSMEbtt77pWeB618W824aGVxhLhPEPaCUMGMvBhuk

Desired python echo

echo.py
I am 16Uiu2HAmRxqPcNXm9KAUAVKyQkpXF8c8r7S6jdpGK6K963w9Puwk
Listener ready, listening on:
/ip4/127.0.0.1/tcp/10333/p2p/16Uiu2HAmRxqPcNXm9KAUAVKyQkpXF8c8r7S6jdpGK6K963w9Puwk
/ip4/192.168.136.148/tcp/10333/p2p/16Uiu2HAmRxqPcNXm9KAUAVKyQkpXF8c8r7S6jdpGK6K963w9Puwk
/ip4/10.149.6.41/tcp/10333/p2p/16Uiu2HAmRxqPcNXm9KAUAVKyQkpXF8c8r7S6jdpGK6K963w9Puwk

Run this from the same folder in another console:

echo-demo -d /ip4/192.168.136.148/tcp/33387/p2p/16Uiu2HAmRxqPcNXm9KAUAVKyQkpXF8c8r7S6jdpGK6K963w9Puwk

Waiting for incoming connections...

Got it exposing all available interfaces. @acul71

acul71 · 2025-08-10T16:07:02Z

@yashksaini-coder
Great work just follow this mods:

Summary: yashksaini-coder's Thin Waist Address Validation PR

🎯 Quick Assessment

Overall: Excellent foundation, needs minor refinements for JavaScript parity.

Status: Phase 1 ✅ Complete, Phase 2 🔄 Partially Complete

✅ What's Working Well

Core utilities: Robust, well-tested, proper error handling
Backward compatibility: Graceful fallbacks when Thin Waist unavailable
Test coverage: Comprehensive unit and integration tests
Type safety: Full type annotations throughout

🔧 Key Issues to Fix

1. JavaScript Parity (High Priority)

Problem: Echo shows only 1 address instead of multiple interfaces like JS libp2p.

Current:

/ip4/192.168.136.148/tcp/8000/p2p/16Uiu2...

Target (like JS):

/ip4/127.0.0.1/tcp/8000/p2p/16Uiu2...
/ip4/192.168.136.148/tcp/8000/p2p/16Uiu2...
/ip4/10.149.6.41/tcp/8000/p2p/16Uiu2...

Fix: Use get_available_interfaces() instead of get_optimal_binding_address()

2. Missing Loopback (High Priority)

Problem: No 127.0.0.1 in output.

Fix: Add loopback to get_available_interfaces():

addrs.append(Multiaddr(f"/ip4/127.0.0.1/{protocol}/{port}"))

3. Command Display (Medium Priority)

Problem: echo-demo -d shows 0.0.0.0 instead of concrete address.

Fix: Use first expanded address instead of host.get_addrs()[0]

🚀 Quick Wins

Replace this line in echo.py:

listen_addr = get_optimal_binding_address(port)

With:

listen_addrs = get_available_interfaces(port)

Add loopback to address validation:

# In get_available_interfaces()
addrs.append(Multiaddr(f"/ip4/127.0.0.1/{protocol}/{port}"))

Update display logic:

# Show all addresses
for addr in listen_addrs:
    print(f"{addr}/p2p/{host.get_id().to_string()}")

📋 Action Items

High Priority

Fix JavaScript parity (multiple interface display)
Add loopback interface (127.0.0.1)
Fix command generation (use concrete addresses)

Medium Priority

Improve random port handling
Add IPv6 loopback support
Enhanced error messages

🏆 Recommendation

Approve with minor revisions. The core implementation is solid - just needs these small tweaks to match JavaScript libp2p behavior.

🧪 Test Status

✅ Unit Tests - All Passing

test_get_available_interfaces() ✅
test_get_optimal_binding_address() ✅
test_expand_wildcard_address_ipv4() ✅
test_expand_wildcard_address_port_override() ✅
test_expand_wildcard_address_ipv6() ✅

❌ Integration Test - Failing

Problem: test_echo_thin_waist.py expects log messages that don't exist in current echo.py.

Test expects:

"Selected binding address:"
"Available candidate interfaces:"

Current echo.py outputs:

"I am {peer_id}"
"echo-demo -d {address}"
"Waiting for incoming connections..."

Fix: Update integration test to match actual echo.py output format.

💡 Pro Tips

Test with: python examples/echo/echo.py -p 8000
Compare with: JavaScript libp2p output format
Focus on: User experience consistency across implementations
Remember: Loopback is crucial for local development

Bottom Line: Great work! Just need to show all interfaces like JavaScript libp2p does. 🚀

yashksaini-coder · 2025-08-11T06:25:44Z

@acul71 got it this clears a lot, I will focus on the javascript libp2p interface showcase.

yashksaini-coder added 3 commits August 9, 2025 01:22

Refactor echo example to use optimal binding address

fa17423

- Replaced hardcoded listen address with `get_optimal_binding_address` for improved flexibility. - Imported address validation utilities in `echo.py` and updated `__init__.py` to include new functions.

Merge branch 'main' into feat/804-add-thin-waist-address

09cd8b3

acul71 reviewed Aug 10, 2025

View reviewed changes

Merge branch 'main' into feat/804-add-thin-waist-address

a14c42e

Merge branch 'libp2p:main' into feat/804-add-thin-waist-address

9a0f224

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

✨ Feat: add Thin Waist address validation utilities and integrate into echo example #811

✨ Feat: add Thin Waist address validation utilities and integrate into echo example #811

yashksaini-coder commented Aug 8, 2025

Uh oh!

acul71 commented Aug 9, 2025

Uh oh!

yashksaini-coder commented Aug 10, 2025

Uh oh!

acul71 Aug 10, 2025

Uh oh!

yashksaini-coder Aug 10, 2025

Uh oh!

acul71 commented Aug 10, 2025 •

edited

Loading

Uh oh!

yashksaini-coder commented Aug 10, 2025

Uh oh!

acul71 commented Aug 10, 2025 •

edited

Loading

Uh oh!

yashksaini-coder commented Aug 11, 2025

Uh oh!

Uh oh!

✨ Feat: add Thin Waist address validation utilities and integrate into echo example #811

Are you sure you want to change the base?

✨ Feat: add Thin Waist address validation utilities and integrate into echo example #811

Conversation

yashksaini-coder commented Aug 8, 2025

What was wrong?

How was it fixed?

Why

Backward Compatibility

To-Do

Uh oh!

acul71 commented Aug 9, 2025

Uh oh!

yashksaini-coder commented Aug 10, 2025

Uh oh!

acul71 Aug 10, 2025

Choose a reason for hiding this comment

Uh oh!

yashksaini-coder Aug 10, 2025

Choose a reason for hiding this comment

Uh oh!

acul71 commented Aug 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yashksaini-coder commented Aug 10, 2025

Uh oh!

acul71 commented Aug 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary: yashksaini-coder's Thin Waist Address Validation PR

🎯 Quick Assessment

✅ What's Working Well

🔧 Key Issues to Fix

1. JavaScript Parity (High Priority)

2. Missing Loopback (High Priority)

3. Command Display (Medium Priority)

🚀 Quick Wins

📋 Action Items

High Priority

Medium Priority

🏆 Recommendation

🧪 Test Status

✅ Unit Tests - All Passing

❌ Integration Test - Failing

💡 Pro Tips

Uh oh!

yashksaini-coder commented Aug 11, 2025

Uh oh!

Uh oh!

acul71 commented Aug 10, 2025 •

edited

Loading

acul71 commented Aug 10, 2025 •

edited

Loading